W3C Working Draft, 18 December 2021

Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Media Queries allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and JavaScript.

Media Queries Level 5 describes the mechanism and syntax of media queries, media types, and media features. It extends and supersedes the features defined in Media Queries Level 4.

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the CSS Working Group as a Working Draft using the Recommendation track. Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “mediaqueries” in the title, like this: “[mediaqueries] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list [email protected].

This document is governed by the 2 November 2021 W3C Process Document.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

The following features are at-risk, and may be dropped during the CR period:

“At-risk” is a W3C Process term-of-art, and does not necessarily imply that the feature is in danger of being dropped or delayed. It means that the WG believes the feature may have difficulty being interoperably implemented in a timely manner, and marking it as such allows the WG to drop the feature if necessary when transitioning to the Proposed Rec stage, without having to publish a new Candidate Rec without the feature first.

This section is not normative.

In 1997, HTML4 [HTML401] defined a mechanism to support media-dependent style sheets, tailored for different media types. For example, a document may use different style sheets for screen and for print. In HTML, this can be written as:

CSS adapted and extended this functionality with its @media and @import rules, adding the ability to query the value of individual features:

Similarly, stylesheets can be conditionally imported based on media queries:

Media queries can be used with HTML, XHTML, XML [xml-stylesheet] and the @import and @media rules of CSS.

This module extends and supersedes [MEDIAQUERIES-4] and its predecessor [MEDIAQUERIES-3], which themselves built upon and replaced CSS 2 § 7 Media types.

Value types not defined in this specification, such as , or , are defined in [CSS-VALUES-4]. Other CSS modules may expand the definitions of these value types.

The units used in media queries are the same as in other parts of CSS, as defined in [CSS-VALUES-4]. For example, the pixel unit represents CSS pixels and not physical pixels.

Relative length units in media queries are based on the initial value, which means that units are never based on results of declarations.

Note: For example, in HTML, the em unit is relative to the initial value of font-size, defined by the user agent or the user’s preferences, not any styling on the page. Note that this will also take into account additional restrictions the user might apply, such as minimum font sizes.

User agents and developers implementing this specification need to be aware of this vector and take it into consideration when deciding whether to use the feature. Specifically `prefers-reduced-motion`, `prefers-color-scheme` and `prefers-reduced-data` are currently of concern for exploitation.

A media query is a method of testing certain aspects of the user agent or device that the document is being displayed in. Media queries are (almost) always independent of the contents of the document, its styling, or any other internal aspect; they’re only dependent on “external” information unless another feature explicitly specifies that it affects the resolution of Media Queries.

The syntax of a media query consists of an optional media query modifier, an optional media type, and zero or more media features:

A media query is a logical expression that is either true or false. A media query is true if:

the media type, if specified, matches the media type of the device where the user agent is running, and

the media condition is true.

Statements regarding media queries in this section assume the syntax section is followed. Media queries that do not conform to the syntax are discussed in § 3.2 Error Handling. I.e. the syntax takes precedence over requirements in this section.

This example expresses that a certain style sheet (example.css) applies to devices of a certain media type (screen) with certain feature (it must be a color screen).

Here is the same media query written in an @import-rule in CSS:

User agents must re-evaluate media queries in response to changes in the user environment that they’re aware of, for example if the device is tiled from landscape to portrait orientation, and change the behavior of any constructs dependent on those media queries accordingly.

Unless another feature explicitly specifies that it affects the resolution of Media Queries, it is never necessary to apply a style sheet in order to evaluate expressions.

Several media queries can be combined into a comma-separated media query list.

A media query list is true if any of its component media queries are true, and false only if all of its component media queries are false.

An empty media query list evaluates to true.

A media query may optionally be prefixed by a single media query modifier, which is a single keyword which alters the meaning of the following media query.

An individual media query can have its result negated by prefixing it with the keyword not. If the media query would normally evaluate to true, prefixing it with not makes it evaluate to false, and vice versa.

The concept of media queries originates from HTML4 [HTML401]. That specification only defined media types, but had a forward-compatible syntax that accommodated the addition of future concepts like media features: it would consume the characters of a media query up to the first non-alphanumeric character, and interpret that as a media type, ignoring the rest. For example, the media query screen and (color) would be truncated to just screen.

Unfortunately, this means that legacy user agents using this error-handling behavior will ignore any media features in a media query, even if they’re far more important than the media type in the query. This can result in styles accidentally being applied in inappropriate situations.

To hide these media queries from legacy user agents, the media query can be prefixed with the keyword only. The only keyword has no effect on the media query’s result, but will cause the media query to be parsed by legacy user agents as specifying the unknown media type “only”, and thus be ignored.

Note: Note that the only keyword can only be used before a media type. A media query consisting only of media features, or one with another media query modifier like not, will be treated as false by legacy user agents automatically.

Note: At the time of publishing this specification, such legacy user agents are extremely rare, and so using the only modifier is rarely, if ever, necessary.

A media type is a broad category of user-agent devices on which a document may be displayed. The original set of media types were defined in HTML4, for the media attribute on elements.

Unfortunately, media types have proven insufficient as a way of discriminating between devices with different styling needs. Some categories which were originally quite distinct, such as screen and handheld, have blended significantly in the years since their invention. Others, such as tty or tv, expose useful differences from the norm of a full-featured computer monitor, and so are potentially useful to target with different styling, but the definition of media types as mutually exclusive makes it difficult to use them in a reasonable manner; instead, their exclusive aspects are better expressed as media features such as grid or scan.

As such, the following media types are defined for use in media queries:

In addition, the following deprecated media types are defined. Authors must not use these media types; instead, it is recommended that they select appropriate media features that better represent the aspect of the device that they are attempting to style against.

User agents must recognize the following media types as valid, but must make them match nothing.

Note: It is expected that all of the media types will also be deprecated in time, as appropriate media features are defined which capture their important differences.

A media feature is a more fine-grained test than media types, testing a single, specific feature of the user agent or display device.

Syntactically, media features resemble CSS properties: they consist of a feature name, a colon, and a value to test for. They may also be written in boolean form as just a feature name, or in range form with a comparison operator.

There are, however, several important differences between properties and media features:

If a media feature references a concept which does not exist on the device where the UA is running (for example, speech UAs do not have a concept of “width”), the media feature must always evaluate to false.

Every media feature defines its “type” as either “range” or “discrete” in its definition table.

“Discrete” media features, like pointer take their values from a set. The values may be keywords or boolean numbers (0 and 1), but the common factor is that there’s no intrinsic “order” to them—none of the values are “less than” or “greater than” each other.

“Range” media features like width, on the other hand, take their values from a range. Any two values can be compared to see which is lesser and which is greater.

The only significant difference between the two types is that “range” media features can be evaluated in a range context and accept “min-” and “max-” prefixes on their name. Doing either of these changes the meaning of the feature—rather than the media feature being true when the feature exactly matches the given value, it matches when the feature is greater than/less than/equal to the given value.

On the other hand, (width: 600px) by itself is only true when the viewport’s width is exactly 600px. If it’s less or greater than 600px, it’ll be false.

While media features normally have a syntax similar to CSS properties, they can also be written more simply as just the feature name, like (color).

When written like this, the media feature is evaluated in a boolean context. If the feature would be true for any value other than the number 0, a with the value 0, the keyword none, or a value explicitly defined by that media feature to evaluate as false in a boolean context, the media feature evaluates to true. Otherwise, it evaluates to false.

For example, update is typically written as (update) to test if any kind of updating is available, or not (update) to check for the opposite.

It can still be given an explicit value as well, with (update: fast) or (update: slow) equal to (update), and (update: none) equal to not (update).

For example, (pointer) is useful, as pointer has a none value to indicate there’s no pointing device at all on the device. On the other hand, (scan) is just always true or always false (depending on whether it applies at all to the device), as there’s no value that means “false”.

Media features with a “range” type can be alternately written in a range context that takes advantage of the fact that their values are ordered, using ordinary mathematical comparison operators:

The remaining forms, with the feature name nested between two value comparisons, returns true if both comparisons are true.

Some media features with a "range" type are said to be false in the negative range. This means that negative values are valid and must be parsed, and that querying whether the media feature is equal to, less than, or less or equal than any such negative value must evaluate to false. Querying whether the media feature is greater, or greater or equal, than a negative value evaluates to true if the relationship is true.

Note: If negative values had been rejected at parse time instead, they would be treated as unknown based on the error handling rules. However, in reality, whether a device’s resolution is -300dpi is not unknown, it is known to be false. Similarly, for any visual device, the width of the targeted display area is known to be greater than -200px The above rule reflects that, making intuition match what UAs do.

Rather than evaluating a “range” type media feature in a range context, as described above, the feature may be written as a normal media feature, but with a “min-” or “max-” prefix on the feature name.

This is equivalent to evaluating the feature in a range context, as follows:

If different color components are represented by different number of bits, the smallest number is used.

In a device with indexed colors, the minimum number of bits per color component in the lookup table is used.

Note: The described functionality is only able to describe color capabilities at a superficial level. color-gamut, is generally more relevant to authors’ needs. If further functionality is required, RFC2879 [RFC2879] provides more specific media features which may be supported at a later stage.

The color-index media feature describes the number of entries in the color lookup table of the output device. If the device does not use a color lookup table, the value is zero.

color-index is false in the negative range.

The monochrome media feature describes the number of bits per pixel in a monochrome frame buffer. If the device is not a monochrome device, the output device value will be 0.

monochrome is false in the negative range.

The color-gamut media feature describes the approximate range of colors that are supported by the UA and output device. That is, if the UA receives content with colors in the specified space it can cause the output device to render the appropriate color, or something appropriately close enough.

Note: The query uses approximate ranges for a few reasons. Firstly, there are a lot of differences in display hardware. For example, a device might claim to support "Rec. 2020", but actually renders a significantly lower range of the full gamut. Secondly, there are a lot of different color ranges that different devices support, and enumerating them all would be tedious. In most cases the author does not need to know the exact capabilities of the display, just whether it is better than sRGB, or significantly better than sRGB. That way they can serve appropriate images, tagged with color profiles, to the user.

Note: It is expected that the vast majority of color displays will be able to return true to a query of this type.

Note: The p3 gamut is larger than and includes the srgb gamut.

Note: The rec2020 gamut is larger than and includes the p3 gamut.

The following table lists the primary colors of these color spaces in terms of their color space chromaticity coordinates, as defined in [COLORIMETRY].

Note: The table above does not contains enough information to fully describe the color spaces, but is sufficient to determine whether an output device approximately covers their respective gamuts. See [SRGB] for more information on sRGB, [SMPTE-EG-432-1-2010] and [SMPTE-RP-431-2-2011] for more information on DCI P3, and [ITU-R-BT-2020-2] for more information on ITU-R Recommendation BT.2020.

Note: An output device can return true for multiple values of this media feature, if its full output gamut is large enough, or one gamut is a subset of another supported gamut. As a result, this feature is best used in an "ascending" fashion—set a base value when (color-gamut: srgb) is true, then override it if (color-gamut: p3) is true, etc.

Note: Some output devices, such as monochrome displays, cannot support even the srgb gamut. To test for these devices, you can use this feature in a negated boolean-context fashion: not (color-gamut).

dynamic-range represents the combination of max brightness, color depth, and contrast ratio that are supported by the user agent and output device.

they support a high peak brightness

they support a high contrast ratio

the color depth is greater than 24 bit or 8 bit per color component of RGB

Note: Some devices have high dynamic range capabilities that are not always on, and that need to be activated (sometimes programmatically, sometimes by the user, sometimes based on the content). This media feature does not test whether such a mode is active, just whether the device is capable of high dynamic range visuals.

Note: More than one value of this media feature can match simulataneously: a user agent matching high will also match standard.

Peak brightness refers to how bright the brightest point a light-emitting device such as an LCD screen can produce, or in the case of a light reflective device such as paper or e-ink, the point at which it least absorbs light.

Note: Some devices can only produce their peak brightness for brief periods of time or on a small portion of their surface at any given time.

The contrast ratio is the ratio of the luminance of the brightest color to that of the darkest color that the system is capable of producing.

This specification does not define precise ways by which these qualities can be measured; it also lets the user agent determine what counts as a high contrast ratio and as a high peak brightness. User agents must nonetheless attempt to conform to the following intent: a device capable of high peak brightness can display “brighter than white” highlights, and a simultaneous ability to do so while also presenting deep blacks (rather than an overall bright but washed out image) is indicative of a high contrast ratio.

Note: The determination for dynamic-range and video-dynamic-range will be vary depending on the user agent, but is expected to have broadly dependable semantics.

The inverted-colors media feature indicates whether the content is displayed normally, or whether colors have been inverted.

Note: This is an indication that the user agent or underlying operating system has forcibly inverted all colors, not a request to do so. This is sometimes provided as a simple accessibility feature, allowing users to switch between light-on-dark and dark-on-light text. However, this has unpleasant side effects, such as inverting pictures, or turning shadows into highlights, which reduce the readability of the content.

This value must not match if the user agent has done some kind of content aware inversion such as one that preserves the images (except through its UA style sheet, see below).

Note: This is because the goal of this media feature is to enable authors to mitigate the undesirable effects of the non content aware approach that invert all the pixels. If the author were to take counter measures even in the content-aware cases, their counter measures and the UA’s would be at risk of cancelling each other.

User agents must add the following rule to their UA style sheet:

The “interaction” media features reflect various aspects of how the user interacts with the page.

The pointer and hover features relate to the characteristics of the “primary” pointing device, while any-pointer and any-hover can be used to query the properties of all potentially available pointing devices.

Note: While this specification does not define how user agents should decide what the “primary” pointing device is, the expectation is that user agents should make this determination by combining knowledge about the device/environment they are running on, the number and type of pointing devices available, and a notion of which of these is generally and/or currently being used. In situations where the primary input mechanism for a device is not a pointing device, but there is a secondary – and less frequently used – input that is a pointing devices, the user agent may decide to treat the non-pointing device as the primary (resulting in 'pointer: none'). user agents may also decide to dynamically change what type of pointing device is deemed to be primary, in response to changes in the user environment or in the way the user is interacting with the UA.

Note: The pointer, hover, any-pointer and any-hover features only relate to the characteristics, or the complete absence, of pointing devices, and can not be used to detect the presence of non-pointing device input mechanisms such as keyboards. Authors should take into account the potential presence of non-pointing device inputs, regardless of which values are matched when querying these features.

The pointer media feature is used to query the presence and accuracy of a pointing device such as a mouse. If multiple pointing devices are present, the pointer media feature must reflect the characteristics of the “primary” pointing device, as determined by the user agent. (To query the capabilities of any available pointing devices, see the any-pointer media feature.)

Both coarse and fine indicate the presence of a pointing device, but differ in accuracy. A pointing device with which it would be difficult or impossible to reliably pick one of several small adjacent targets at a zoom factor of 1 would qualify as coarse. Changing the zoom level does not affect the value of this media feature.

Note: As the UA may provide the user with the ability to zoom, or as secondary pointing devices may have a different accuracy, the user may be able to perform accurate clicks even if the value of this media feature is coarse. This media feature does not indicate that the user will never be able to click accurately, only that it is inconvenient for them to do so. Authors are expected to react to a value of coarse by designing pages that do not rely on accurate clicking to be operated.

For accessibility reasons, even on devices whose pointing device can be described as fine, the UA may give a value of coarse or none to this media query, to indicate that the user has difficulties manipulating the pointing device accurately or at all. In addition, even if the primary pointing device has fine pointing accuracy, there may be additional coarse pointing devices available to the user. Authors may wish to query the any-pointer media feature to take these other coarse potential pointing devices into account.

The hover media feature is used to query the user’s ability to hover over elements on the page with the primary pointing device. If a device has multiple pointing devices, the hover media feature must reflect the characteristics of the “primary” pointing device, as determined by the user agent. (To query the capabilities of any available pointing devices, see the any-hover media feature.)

Pointing devices that can hover, but for which doing so is inconvenient and not part of the normal way they are used, also match this value. For example, a touchscreen where a long press is treated as hovering would match hover: none.

However, despite this, the optional mouse does allow users to hover. Authors should therefore be careful not to assume that the ':hover' pseudo class will never match on a device where 'hover:none' is true, but they should design layouts that do not depend on hovering to be fully usable.

For accessibility reasons, even on devices that do support hovering, the UA may give a value of hover: none to this media query, to opt into layouts that work well without hovering. Note that even if the primary input mechanism has 'hover: hover' capability, there may be additional input mechanisms available to the user that do not provide hover capabilities.

The any-pointer and any-hover media features are identical to the pointer and hover media features, but they correspond to the union of capabilities of all the pointing devices available to the user. In the case of any-pointer, more than one of the values can match, if different pointing devices have different characteristics.

any-pointer and any-hover must only match none if all of the pointing devices would match none for the corresponding query, or there are no pointing devices at all.

A browser in such a smart TV would have coarse as the value of both pointer and any-pointer, allowing authors to provide a layout with large and easy to reach click targets.

The user may also have paired a Bluetooth mouse with the TV, and occasionally use it for extra convenience, but this mouse is not the main way the TV is operated. pointer still matches coarse, while any-pointer now both matches coarse and fine.

Switching to small click targets based on the fact that (any-pointer: fine) is now true would not be appropriate. It would not only surprise the user by providing an experience out of line with what they expect on a TV, but may also be quite inconvenient: the mouse, not being the primary way to control the TV, may be out of reach, hidden under one of the cushions on the sofa...

By contrast, consider scrolling on the same TV. Scrollbars are difficult to manipulate without an accurate pointing device. Having prepared an alternative way to indicate that there is more content to be seen based on (pointer: coarse) being true, an author may want to still show the scrollbars in addition if (any-pointer: fine) is true, or to hide them altogether to reduce visual clutter if (any-pointer: fine) is false.

The nav-controls media features allows authors to know whether the user agent is providing obviously discoverable navigation controls as part of its user interface.

Note: Traditional browsers typically do provide such controls and web pages typically have not needed to concern themselves with that, but in some contexts, web applications are run through so-called web-views, which do not always feature a full-fledged user interface. It is thus useful for authors to know what is being supplied by the user agent, so that they can consider whether they need to provide an easily discovered alternative.

In this context, obviously discoverable refers to controls which are either directly visible in the user interface, such as buttons, or some other form of control which is typical of the user interface of that device and trivially identifiable by the user. In the case of visual user interfaces, this would typically a visible control, although it could be something else in the case of an audio or tactile user interface. Importantly, this is not about keyboard shortcuts or gestures; as convenient as these can be, these are not obviously discoverable by just looking at (in the case of a visual UI) the user agent.

The following values are valid:

As this media feature can be used in a boolean context, the same example can be written with shorter syntax:

Note: Theoretically, the two are not strictly equivalent, as there could be new values in a future extension of this media feature other than back that could match when back doesn’t. In that case, using the nav-controls feature in a boolean context could be misleading. However, given that navigation back is arguably the most fundamental navigation operation, the CSS Working Group does not anticipate user interfaces with explicit navigation controls but no back button, so this problem is not expected to occur in practice.

Whether obviously discoverable controls are active does not impact the evaluation of this media feature.

Some user agents, including many TVs, render video and graphics in two separate "planes" (bi-plane) with distinct screen characteristics. A set of video-prefixed features is provided to describe the video plane.

Any bi-plane implementation must return values based on the video plane for the following features: video-color-gamut; video-dynamic-range. All other features must return values based on the graphics plane.

Non bi-plane implementations must return the same values for video-prefixed features and their non-prefixed counterparts.

The video-color-gamut media feature describes the approximate range of colors that are supported by the UA and output device’s video plane. That is, if the UA receives content with colors in the specified space it can cause the output device to render the appropriate color, or something appropriately close enough.

Value and color space definitions are the same as color-gamut

video-dynamic-range represents the combination of max brightness, color depth, and contrast ratio that are supported by the UA and output device’s video plane.

Supported values are the same as dynamic-range.

The scripting media feature is used to query whether scripting languages, such as JavaScript, are supported on the current document.

Should there be an explicit minimum threshold to meet before a UA is allowed to claim initial-only? Having one would mean authors would know what they can depend on, and could tailor their scripts accordingly. On the other hand, pinpointing that threshold is difficult: if it is set too low, the scripting facilities that authors can depend on may be to constrained to be practical, even though actual UAs may potentially all support significantly more. But trying to set it higher may cause us to exclude UAs that do support scripting at loading time, but restrict it in some cases based on complex heuristics. For instance, conservative definitions likely include at least running all inline scripts and firing the DOMContentLoaded event. But it does not seem useful for authors to constrain themselves to this if most (or maybe all) initial-only UAs also load external scripts (including async and defer) and fire the load event. On the other hand, requiring external scripts to be loaded and the load event to be fired could exclude UAs like Opera mini, which typically do run them, but may decide not to based on timeouts and other heuristics. [Issue #503]

Some user agents have the ability to turn off scripting support on a per script basis or per domain basis, allowing some, but not all, scripts to run in a particular document. The scripting media feature does not allow fine grained detection of which script is allowed to run. In this scenario, the value of the scripting media feature should be enabled or initial-only if scripts originating on the same domain as the document are allowed to run, and none otherwise.

Note: A future level of CSS may extend this media feature to allow fine-grained detection of which script is allowed to run.

When designing documents that use media queries, the same media query may be used in multiple places, such as to qualify multiple @import statements. Repeating the same media query multiple times is an editing hazard; an author making a change must edit every copy in the same way, or suffer from difficult-to-find bugs in their CSS.

To help ameliorate this, this specification defines a method of defining custom media queries, which are simply-named aliases for longer and more complex media queries. In this way, a media query used in multiple places can instead be assigned to a custom media query, which can be used everywhere, and editing the media query requires touching only one line of code.

A custom media query is defined with the @custom-media rule:

The can then be used in a media feature. It must be used in a boolean context; using them in a normal or range context is a syntax error. If a is given, the custom media query evaluates to true if the it represents evaluates to true, and false otherwise. If true or false is given, the custom media query evaluates to true or false, respectively.

It is equivalent to:

Processing it as if it meant the following would be incorrect:

A @custom-media rule can refer to other custom media queries. However, loops are forbidden, and a custom media query must not be defined in terms of itself or of another custom media query that directly or indirectly refers to it. Any such attempt of defining a custom media query with a circular dependency must cause all the custom media queries in the loop to fail to be defined.

If multiple @custom-media rules declare the same , the truth value is based on the last one alone, ignoring all previous declarations of the same .

Note: For error handling purposes, an undefined media feature is different from a media feature that evaluates to false. See Media Queries 4 § 3.2 Error Handling for details.

The prefers-reduced-motion media feature is used to detect if the user has requested the system minimize the amount of animation or motion it uses.

The prefers-reduced-transparency media feature is used to detect if the user has requested the system minimize the amount of transparent or translucent layer effects it uses.

How does this interact with preferences around e.g. pattern fills and backgrounds? They’re not about transparency, but they also interfere with shape recognition.

The prefers-contrast media feature is used to detect if the user has requested more or less contrast in the page. This could be responded to, for example, by adjusting the contrast ratio between adjacent colors, or by changing how much elements stand out visually, such as by adjusting their borders.

Note: This value will match for users of forced colors mode who have picked a palette that is neither particularly high nor low contrast. See § 11.4 Detecting Forced Colors Mode: the forced-colors feature.

Using an unqualified @media (prefers-contrast) { … } to apply high contrast styles is incorrect and user-hostile, as it would also impose high contrast styles to people who have requested the exact opposite.

However, it is also common to reduce visual clutter and color complexity in response to both high and low contrast preferences. In that case, it is appropriate to use @media (prefers-contrast) { … } without specifying more or less, to do things like replacing background images with plain colors, turning off decorative gradients, or replacing border images or box shadows with simple solid borders. As prefers-contrast: custom—like prefers-contrast: more or prefers-contrast: less—evaluates to true in a boolean context, such simplifications would also benefit users of forced colors mode, even when their colors of choice do not result in a particularly high or low contrast. This is desirable, as the reduced palette enforced by forced colors mode calls for some visual simplification of the page.

This list should be refined and expanded.

In addition to forced-colors: active, the user agent must also match one of prefers-contrast: more or prefers-contrast: less if it can determine that the forced color palette chosen by the user has a particularly high or low contrast, and must make prefers-contrast: custom match otherwise.

Similarly, if the forced color palette chosen by the user fits within one of the color schemes described by prefers-color-scheme, the corresponding value must also match.

The prefers-color-scheme media feature reflects the user’s desire that the page use a light or dark color theme.

Note: The values for this feature might be expanded in the future (to express a more active preference for light color schemes, or preferences for other types of color schemes like "sepia"). As such, the most future-friendly way to use this media feature is by negation such as (prefers-color-scheme: dark) and (not (prefers-color-scheme: dark)), which ensures that new values fall into at least one of the styling blocks.

The method by which the user expresses their preference can vary. It might be a system-wide setting exposed by the Operating System, or a setting controlled by the user agent.

Note: User preferences can also vary by medium. For example, a user may prefer dark themes on a glowing screen, but light themes when printing (to save ink and/or because inked text on blank paper prints better than blank letterforms knocked out of an inked background). UAs are expected to take such variances into consideration so that prefers-color-scheme reflects preferences appropriate to the medium rather than preferences taken out of context.

If a future user agent wishes to expose a difference between "no preference" and "really wants a light display", please contact the CSSWG to discuss this.

This feature may be an undesired source of fingerprinting, with a bias towards low income with limited data. A Privacy and Security section should be added to this spec, and it should address this concern. [Issue #4832]

The prefers-reduced-data media feature is used to detect if the user has a preference for being served alternate content that uses less data for the page to be rendered.

The method by which the user expresses their preference can vary. It might be a system-wide setting exposed by the Operating System, or a setting controlled by the user agent.

Note: User agents may consider setting this based on the same user or system preference as they use to set the Save-Data HTTP request header.

User agents may have explicit settings allowing users to indicate their preferences or may make the determination based on settings in the underlying operating system. User agents may also automatically infer the preferences of the user based on knowledge about the device, the environment, etc. In such case, it is recommended that they also offer a way for users to opt out of or override the automatically determined preferences.

For instance, liquid crystal displays can be washed out and very hard to read in brightly lit environments. A device with such a screen and with an ambient light sensor could automatically switch prefers-contrast to more when it detects conditions that would make the screen difficult to read. A user agent on a device with an e-ink display would not make the same adjustment, as such displays remain readable in bright daylight.

In the opposite situation, user agents running of device with a light-emitting screen (LCD, OLED, etc.) and an ambient light sensor could automatically switch prefers-contrast to less and prefers-color-scheme to dark when used in a dim environment where excessive contrast and brightness would be distracting or uncomfortable to the reader.

The following media features are deprecated. They are kept for backward compatibility, but are not appropriate for newly written style sheets. Authors must not use them. User agents must support them as specified.

To query for the size of the viewport (or the page box on page media), the width, height and aspect-ratio media features should be used, rather than device-width, device-height and device-aspect-ratio, which refer to the physical size of the device regardless of how much space is available for the document being laid out. The device-* media features are also sometimes used as a proxy to detect mobile devices. Instead, authors should use media features that better represent the aspect of the device that they are attempting to style against.

The device-width media feature describes the width of the rendering surface of the output device. For continuous media, this is the width of the Web-exposed screen area. For paged media, this is the width of the page sheet size.

device-width is false in the negative range.

In the example above, the style sheet will apply only to screens less than 800px in length. The px unit is of the logical kind, as described in the Units section.

Note: If a device can be used in multiple orientations, such as portrait and landscape, the device-* media features reflect the current orientation.

The device-height media feature describes the height of the rendering surface of the output device. For continuous media, this is the height of the Web-exposed screen area. For paged media, this is the height of the page sheet size.

device-height is false in the negative range.

In the example above, the style sheet will apply only to screens taller than 600 vertical pixels. Note that the definition of the px unit is the same as in other parts of CSS.

The 'device-aspect-ratio media feature is defined as the ratio of the value of the device-width media feature to the value of the 'device-height media feature.

This section is not normative.

this section is incomplete

The display-mode media feature allows an origin access to aspects of a user’s local computing environment and, particularly when used together with an application manifest display member [APPMANIFEST], allows an origin some measure of control over a user agent’s native UI. Through a CSS media query, a script can know the display mode of a web application. An attacker could, in such a case, exploit the fact that an application is being displayed in fullscreen to mimic the user interface of another application.

This section is not normative.

In addition to editorial changes and minor clarifications, the following changes and additions were made to this module since the 2020-07-31 Working Draft:

Adopted display-mode from [APPMANIFEST]. (See Issue 6343)

Dropped the media features what were meant to query about the geometry of the video plane in bi-plane implementations: video-width, video-height, and video-resolution. (See Issue 5044)

Renamed prefers-contrast values high and low to more and prefers-contrast less. (See Issue 2943)

Rework the interaction between prefers-contrast and forced-colors, retiring prefers-contrast: forced and introducing custom. (See Issue 5433) and Issue 6036)

Added the horizontal-viewport-segments and vertical-viewport-segments media feature. (See Issue 6234)

Added the nav-controls media feature. (See Issue 6234)

Make it possible for multiple values of dynamic-range to match at the same time. (See Issue 6793)

The following additions were made to this module since the 2020-07-15 Working Draft:

The following additions were made to this module since the 2020-06-03 Working Draft:

The following additions were made to this module since the 2020-03-18 Working Draft:

The following additions were made to this module since the 2020-03-03 First Public Working Draft:

The following additions were made to the First Public Working Draft of this module since the Media Queries Level 4:

This section is not normative.

This specification is the product of the W3C Working Group on Cascading Style Sheets.

Comments from Adam Argyle, Amelia Bellamy-Royds, Andreas Lind, Andres Galante, Arve Bersvendsen, Björn Höhrmann, Chen Hui Jing, Chris Lilley, Chris Rebert, Christian Biesinger, Christoph Päper, Elika J. Etemad (fantasai), Emilio Cobos Álvarez, François Remy, Frédéric Wang, Fuqiao Xue, Greg Whitworth, Ian Pouncey, James Craig, Jay Harris, Jinfeng Ma, Kivi Shapiro, L. David Baron, Masataka Yakura, Matt Giuca, Melinda Grant, Michael Smith, Nicholas C. Zakas Patrick H. Lauke, Philipp Hoschka, Rick Byers, Rijk van Geijtenbeek, Rik Cabanier, Roger Gimson, Rossen Atanassov, Sam Sneddon, Sigurd Lerstad, Simon Kissane, Simon Pieters, Steven Pemberton, Susan Lesch, Tantek Çelik, Thomas Wisniewski, Vi Nguyen, Xidorn Quan, Yves Lafon, akklesed, and 張俊芝 improved this specification.

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with , like this: UAs MUST provide an accessible alternative.

Conformance to this specification is defined for three conformance classes:

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the [email protected] mailing list.

No properties defined.

User agents and developers implementing this specification need to be aware of this vector and take it into consideration when deciding whether to use the feature. Specifically `prefers-reduced-motion`, `prefers-color-scheme` and `prefers-reduced-data` are currently of concern for exploitation.